/*
 * Copyright 2012-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.boot.web.servlet.server;

import java.util.function.Predicate;
import java.util.function.Supplier;
import java.util.regex.Pattern;

import javax.servlet.http.Cookie;

import org.springframework.boot.web.server.Cookie.SameSite;
import org.springframework.util.Assert;
import org.springframework.util.ObjectUtils;

/**
 * 策略接口，可与 {@link ConfigurableServletWebServerFactory} 实现配合使用，
 * 用于为特定的 {@link Cookie cookies} 提供自定义的 {@link SameSite} 值。
 * <p>
 * 基础的 CookieSameSiteSupplier 实现可以通过 {@code of...} 工厂方法构造，
 * 通常结合名称匹配使用。例如：<pre class="code">
 * CookieSameSiteSupplier.ofLax().whenHasName("mycookie");
 * </pre>
 *
 * @author Phillip Webb
 * @since 2.6.0
 * @see ConfigurableServletWebServerFactory#addCookieSameSiteSuppliers(CookieSameSiteSupplier...)
 */
@FunctionalInterface
public interface CookieSameSiteSupplier {

	/**
	 * 获取应当用于给定 {@link Cookie} 的 {@link SameSite} 值。
	 * @param cookie 要检查的 Cookie
	 * @return 要使用的 {@link SameSite} 值，如果返回 {@code null} 表示应检查下一个供应者
	 */
	SameSite getSameSite(Cookie cookie);

	/**
	 * 限制该供应者仅在 Cookie 名称匹配指定名称时被调用。
	 * @param name 要匹配的名称
	 * @return 一个新的 {@link CookieSameSiteSupplier}，仅在名称匹配时调用此供应者
	 */
	default CookieSameSiteSupplier whenHasName(String name) {
		Assert.hasText(name, "Name must not be empty");
		return when((cookie) -> ObjectUtils.nullSafeEquals(cookie.getName(), name));
	}

	/**
	 * 限制该供应者仅在 Cookie 名称匹配指定名称提供者返回的名称时被调用。
	 * @param nameSupplier 提供要匹配名称的供应者
	 * @return 一个新的 {@link CookieSameSiteSupplier}，仅在名称匹配时调用此供应者
	 */
	default CookieSameSiteSupplier whenHasName(Supplier<String> nameSupplier) {
		Assert.notNull(nameSupplier, "NameSupplier must not be empty");
		return when((cookie) -> ObjectUtils.nullSafeEquals(cookie.getName(), nameSupplier.get()));
	}

	/**
	 * 限制该供应者仅在 Cookie 名称匹配给定正则表达式时被调用。
	 * @param regex 要匹配的正则表达式
	 * @return 一个新的 {@link CookieSameSiteSupplier}，仅在名称匹配正则时调用此供应者
	 */
	default CookieSameSiteSupplier whenHasNameMatching(String regex) {
		Assert.hasText(regex, "Regex must not be empty");
		return whenHasNameMatching(Pattern.compile(regex));
	}

	/**
	 * 限制该供应者仅在 Cookie 名称匹配给定的 {@link Pattern} 时被调用。
	 * @param pattern 要匹配的正则模式
	 * @return 一个新的 {@link CookieSameSiteSupplier}，仅在名称匹配模式时调用此供应者
	 */
	default CookieSameSiteSupplier whenHasNameMatching(Pattern pattern) {
		Assert.notNull(pattern, "Pattern must not be null");
		return when((cookie) -> pattern.matcher(cookie.getName()).matches());
	}

	/**
	 * 限制该供应者仅在给定的谓词匹配 Cookie 时被调用。
	 * @param predicate 用于匹配 Cookie 的谓词
	 * @return 一个新的 {@link CookieSameSiteSupplier}，仅在 Cookie 满足谓词时调用此供应者
	 */
	default CookieSameSiteSupplier when(Predicate<Cookie> predicate) {
		Assert.notNull(predicate, "Predicate must not be null");
		return (cookie) -> predicate.test(cookie) ? getSameSite(cookie) : null;
	}

	/**
	 * 返回一个新的 {@link CookieSameSiteSupplier}，始终返回 {@link SameSite#NONE}。
	 * @return 供应者实例
	 */
	static CookieSameSiteSupplier ofNone() {
		return of(SameSite.NONE);
	}

	/**
	 * 返回一个新的 {@link CookieSameSiteSupplier}，始终返回 {@link SameSite#LAX}。
	 * @return 供应者实例
	 */
	static CookieSameSiteSupplier ofLax() {
		return of(SameSite.LAX);
	}

	/**
	 * 返回一个新的 {@link CookieSameSiteSupplier}，始终返回 {@link SameSite#STRICT}。
	 * @return 供应者实例
	 */
	static CookieSameSiteSupplier ofStrict() {
		return of(SameSite.STRICT);
	}

	/**
	 * 返回一个新的 {@link CookieSameSiteSupplier}，始终返回给定的 {@link SameSite} 值。
	 * @param sameSite 要返回的 SameSite 值
	 * @return 供应者实例
	 */
	static CookieSameSiteSupplier of(SameSite sameSite) {
		Assert.notNull(sameSite, "SameSite must not be null");
		return (cookie) -> sameSite;
	}

}
